<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>GROOPS - Graphical User Interface (GUI)</title>

    <!-- JQuery and Popper -->
    <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>

    <!-- Bootstrap -->
    <!-- https://getbootstrap.com/docs/4.1/examples/ -->
    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js" integrity="sha384-wfSDF2E50Y2D1uUdj0O3uMBJnjuUD4Ih7YwaYd1iqfktj0Uod8GCExl3Og8ifwB6" crossorigin="anonymous"></script>
    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css" integrity="sha384-Vkoo8x4CGsO3+Hhxv8T/Q5PaXtkKtu6ug5TOeNV6gBiFeWPGFN9MuhOf23Q9Ifjh" crossorigin="anonymous">

    <!-- Mathjax -->
    <script type="text/x-mathjax-config">
    MathJax.Hub.Config({tex2jax: {inlineMath: [ ['$','$'] ],
                                  displayMath: [ ["\\[","\\]"] ],
                                  processEscapes: true},
                        TeX:     {Macros: {M: ["{\\mathbf #1}",1]},
                                  equationNumbers: {autoNumber: "all"}  }});
    </script>
    <script async src="https://cdn.jsdelivr.net/npm/mathjax@2.7.7/MathJax.js?config=TeX-AMS_CHTML" integrity="sha384-e/4/LvThKH1gwzXhdbY2AsjR3rm7LHWyhIG5C0jiRfn8AN2eTN5ILeztWw0H9jmN" crossorigin="anonymous"></script>

    <!-- lunr -->
    <script src="https://cdn.jsdelivr.net/npm/lunr@2.3.8/lunr.min.js" integrity="sha384-vRQ9bDyE0Wnu+lMfm57BlYLO0/XauFuKpVsZPs7KEDwYKktWi5+Kz3MP8++DFlRY" crossorigin="anonymous"></script>

    <!-- Mustache -->
    <script src="https://cdn.jsdelivr.net/npm/mustache@4.0.1/mustache.min.js" integrity="sha384-0PLEZVBpOQ+Kqw3anJWSNWvRxpEFt02tSpBvyRsA4WcvX/OTldWdXxGLVLvh954H" crossorigin="anonymous"></script>

    <!-- GROOPS Stylesheet -->
    <link rel="stylesheet" href="static/groops.css"/>

    <!-- icon -->
    <link rel="icon" href="static/groops_icon.png">

</head>
<body>
    <header>
        <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
            <div class="container">
              <a class="navbar-brand" href="index.html"><img class="logo" src="static/groops_white.svg"></a>
              <div class="collapse navbar-collapse" id="mainNavbar">
                <ul class="navbar-nav mr-auto">
                  <li class="nav-item">
                    <a class="nav-link" href="programType.html">Programs</a>
                  </li>
                  <li class="nav-item">
                    <a class="nav-link" href="classes.html">Classes</a>
                  </li>
                  <li class="nav-item">
                    <a class="nav-link" href="general.parser.html">Parser</a>
                  </li>
                  <li class="nav-item">
                    <a class="nav-link" href="general.fileFormat.html">File Formats</a>
                  </li>
                </ul>
              </div>
                <form class="form-inline my-2 my-lg-0" action="search.html" id="searchTools">
                  <input class="form-control mr-sm-2" placeholder="Search" name="searchTerms" method="GET" value="" type="text" id="searchBox">
                  <button class="btn btn-secondary my-2 my-sm-0" type="submit" id="searchButton">Search</button>
                </form>
              <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#mainNavbar" aria-controls="mainNavbar" aria-expanded="false" aria-label="Toggle navigation" style="">
                <span class="navbar-toggler-icon"></span>
              </button>
            </div>
        </nav>
    </header>
    <main class="container px-0 pt-2 top-buffer">
        <div id="content" class="container">
            <h1 id="general.gui">Graphical User Interface (GUI)</h1><p></p><p>The graphical user interface program <code>groopsGui</code> enables the convenient creation of GROOPS config files.
It uses the <a href="https://qt.io">Qt5 framework</a> for cross-platform support.</p><p><figure><img class="figure" style="width:100%;" src="../figures/gui_overview.png" alt="gui_overview"><figcaption class="center">Figure: Overview of the GUI (components mentioned below marked in red)</figcaption></figure></p><p><h2>Settings and first-time setup</h2><p></p><p>The GUI depends on an XSD schema file containing the complete formal (computer readable) description of a GROOPS config file.
This schema file can be created with the command:
<pre>
  groops --xsd &lt;groopsDir>/groops.xsd
</pre>
At least one schema file has to be set via
the menu <code>Settings - Default Paths and Files</code>. Setting more than one schema files enables the <em>schema selector</em> in the toolbar.
The selected schema will be used when (re-)opening or creating a config file.
This feature is useful when working with different versions of GROOPS at the same time.</p><p>It is possible to set a <em>template file</em> via the menu <code>Settings - Default Paths and Files</code>. This can be any GROOPS config file.
Whenever a new config file is created via the GUI, all global elements and programs defined in the template file are automatically created in the new config file.
It is highly recommended to create a template file containing at least the global element <code>groopsDataDir</code> of type <code>filename</code>.
This element is used as a <a class="groops-ref" href="general.parser.html">variable</a> in most default file paths throughout many GROOPS programs.
Thus, setting the path to the base directory containing all GROOPS data once in the template file, for example as
<strong class="groops-config-element">groopsDataDir</strong>=<code>/home/&lt;user>/groops/data</code>, is the most convenient way to handle default paths in GROOPS.
The template file can also contain other often-used global elements, for example <code>tmpDir</code> or  <code>timeStart</code> and  <code>timeEnd</code>.</p><p>A <em>working directory</em> can be set via <code>Settings - Default Paths and Files</code>.
This directory is used as the default directory in the save dialog of new config files.</p><p>The GUI offers the option to open the GROOPS documentation for a selected program. To use this feature,
the GROOPS documentation must be generated (if not already present) with the command:
<pre>
  groops --doc &lt;groopsDir>/docs/
</pre>
In the menu <code>Settings - Default Paths and Files</code> the path to the HTML version of the documentation must be set (i.e. <code>&lt;groopsDir>/docs/html</code>).
Selecting any program and pressing <code>F1</code> opens the documentation for this program in an external browser.
Pressing <code>F1</code> without having any program selected opens the main page of the GROOPS documentation.</p><p>Executing a config file from the GUI requires the setup of a run command in the menu <code>Settings - Commands</code>.
It is recommended for this command to open a new terminal in which GROOPS is executed with the config file given as an argument.
The placeholders <code>%w</code> and <code>%f</code> are replaced by the directory and file name of the selected config file, respectively.
Multiple commands can be set up, with the option to choose one of them in the run dialog.</p><p>Example commands:
<ul>

	<li>Windows: <code>cd /d %w && groops.exe %f</code>
	</li><li>
Linux (KDE): <code>konsole --workdir %w -e bash -ic "groops %f; bash"</code>
	</li><li>
Linux (GNOME): <code>gnome-terminal --working-directory=%w -x bash -ic "groops %f; bash"</code>
	</li><li>
Windows, MPI with 4 processes: <code>cd /d %w && mpiexec -n 4 groopsMPI.exe %f</code>
	</li><li>
Linux (KDE), MPI with 4 processes: <code>konsole --workdir %w -e bash -ic "mpiexec -n 4 groopsMPI %f; bash"</code>
	</li><li>
Linux (GNOME), MPI with 4 processes: <code>gnome-terminal --working-directory=%w -x bash -ic "mpiexec -n 4 groopsMPI %f; bash"</code>
</li></ul>
</p><p><h2>Basic features</h2><p></p><p>Most basic features used to manipulate a config element are accessible via the context menu,
for example attributing <a class="groops-ref" href="general.loopsAndConditions.html">loops and conditions</a> or setting an element global.
Global elements automatically appear in the dropdown value list of config elements of the same type.
Selecting a global element from the dropdown list as a value links this config element to the global element.
In case the global element is removed, all linked elements' values are replaced by the value of the deleted global element.
Links to global elements imported from other config files via <strong class="groops-config-element">inputfileGlobal</strong>
(see section <a class="groops-ref" href="general.configFiles.html">Config files</a>) can be set using the context menu item <code>Set External Link</code>.</p><p>The sidebar features three widgets:
<ul>

	<li><code>Open Files</code>: An overview of all open config files (select to change current tree)
	</li><li>
<code>Program List</code>: A list of all programs defined in the schema of the active tree (filterable, supports drag and drop to tree, double click appends program)
	</li><li>
<code>Undo Stack</code>: Tracks all changes in a config file (select to change state of tree)
</li></ul>
</p><p>In case the names of programs or config elements change over time, the GUI offers a rename feature to update outdated config files.
The changes must be documented in the schema using GROOPS' rename feature. Affected elements will be marked with an icon and
the context menu item <code>Update name</code> will be available to change the element to the new name defined in the schema.</p><p><h2>Additional keyboard shortcuts</h2><p></p><p><ul>

	<li>Tree navigation:
	<ul>

		</li><li>
<code>Enter</code>: Switch focus from tree to input field of selected row
		</li><li>
<code>Escape</code>: Switch focus from input field back to tree
		</li><li>
<code>Tab</code>: Next sibling element (or next sibling of parent if there is no next sibling, or next child otherwise)
		</li><li>
<code>Shift+Tab</code>: Previous sibling element (or parent if there is no previous sibling)
		</li><li>
<code>Ctrl+Tab</code>: Next tab/tree
		</li><li>
<code>Ctrl+Shift+Tab</code>: Previous tab/tree
		</li><li>
<code>Ctrl+Space</code>: Interact with the element (e.g. filename/program: open dialog; time: switch focus between input fields)
		</li><li>
<code>Ctrl+Up/Down</code>: Next/previous sibling element
		</li><li>
<code>Ctrl+Left/Right</code>: Fold/expand (complex) element
	</li></ul>

	<li>Tree manipulation:
	<ul>

		</li><li>
<code>Ctrl+Shift+Up/Down</code>: Move unbounded list element (e.g. program, layer) up/down
	</li></ul>

	<li>Drag and Drop of tabs to other programs (i.e. text editors) or other GUI windows:
	<ul>

		</li><li>
<code>Drag</code>: Copy tab (= keep in source window)
		</li><li>
<code>Shift+Drag</code>: Move tab (= remove from source window)
	</li></ul>

	<li>Drag and Drop GROOPS config file(s) into GUI:
	<ul>

		</li><li>
<code>Drag</code>: Open file(s) in new tab(s)
		</li><li>
<code>Shift+Drag</code>: Open file in current tab (replaces current tab, only works with a single file)
	</li></ul>

</ul>
</p>

        </div>
    </main>
</body>
</html>
